Current state of optional field parsing with optional

Let’s say we have a record with an optional flag field:

type Sample = { flag ∷ Maybe Boolean }

The appropiate codec for this would look like:

codecSample ∷ JsonCodec Sample
codecSample =
  CAR.object "Sample"
    { flag: CAR.optional CA.boolean
    }

This setup is convenient, as it supports multiple JSON inputs:

• {} is parsed as { flag: Nothing }
• { "flag": true } is parsed as { flag: Just true }
• { "flag": false } is parsed as { flag: Just false }

Introducing optionalWith

However, in many use cases, working with a Maybe Boolean isn’t ideal. Often, we’d prefer to use a plain Boolean, treating both Nothing and Just false as false:

type Sample2 = { flag ∷ Boolean }

With the current version of codec-argonaut, we’d need to define both Sample and Sample2, along with conversion functions between them.

To avoid this, the PR introduces a new modifier: optionalWith, a more flexible version of optional.

optionalWith ∷ ∀ a b. (Maybe a → b) → (b → Maybe a) → CA.JsonCodec a → OptionalWith a b

Here’s how it can be used:

codecSample2 ∷ JsonCodec Sample2
codecSample2 =
  CAR.object "Sample2"
    { flag: CAR.optionalWith
        (fromMaybe false)
        (if _ then Just true else Nothing)
        CA.boolean
    }

This codec handles the following cases directly:

• {} is decoded as { flag: false }
• { "flag": true } is decoded as { flag: true }
• { "flag": false } is decoded as { flag: false }

Other Usecases

This pattern is especially useful when working with JavaScript APIs, where fields are often omitted instead of explicitly set to a default or “empty” value.

Other examples where optionalWith is useful include:

• Omitting empty foreign objects or arrays
• Flattening Maybe (Maybe a) to just Maybe a, useful for fields that can be either null or missing

Bonus:
optionalWith is a generalization of optional, which can now internally be redefined as:

optional = optionalWith identity identity

As a result, this MR introduces no code duplication. Tests are added that verify the behavior.